release: v0.3.0 - #22

sequenceDiagram
    actor User
    participant EmuApp
    participant FileDialog
    participant Fs as Filesystem
    participant GbInstance
    participant CartridgeModule
    participant CartridgeHeader
    participant Audio as AudioGlobals

    User->>EmuApp: Click Open_ROM
    EmuApp->>FileDialog: show_open_dialog(extensions: [gb,zip])
    FileDialog-->>User: Choose_file_path
    User-->>FileDialog: Confirm
    FileDialog-->>EmuApp: Path
    EmuApp->>Fs: read(path)
    Fs-->>EmuApp: Vec_u8_bytes

    alt Bytes_is_ZIP
        EmuApp->>EmuApp: extract_rom_from_bytes(bytes)
        EmuApp-->>EmuApp: rom_bytes
    else Raw_ROM
        EmuApp->>EmuApp: bytes_used_as_rom
    end

    EmuApp->>GbInstance: build_from_bytes(rom_bytes, Some(save_path))
    GbInstance->>CartridgeModule: load_cartridge_from_bytes(rom_bytes, Some(save_path))
    CartridgeModule->>CartridgeHeader: new(rom_bytes)
    CartridgeHeader-->>CartridgeModule: CartridgeHeader
    CartridgeModule-->>GbInstance: (Box_Mbc, GbMode)
    GbInstance->>GbInstance: Determine_GbTypes_from_GbMode
    GbInstance-->>EmuApp: Gb

    EmuApp->>Audio: setup_audio(&mut Gb)
    Audio->>Audio: create_cpal_stream_and_channel()
    Audio-->>EmuApp: AUDIO_PRODUCER_initialized

    EmuApp->>EmuApp: Create_State(gb, rgba_buffer, leftover_audio)
    EmuApp-->>User: ROM_running_with_video_audio

sequenceDiagram
    participant Gb
    participant Cpu

    Note over Gb,Cpu: Each CPU tick
    Gb->>Gb: handle_interrupt()
    Gb->>Cpu: check interrupt_master
    alt Interrupts_disabled
        Gb-->>Cpu: Return_no_interrupt
    else Interrupts_enabled
        Gb->>Gb: pending = ie_flag & if_flag & 0x1F
        alt pending == 0
            Gb-->>Cpu: Return_no_interrupt
        else pending != 0
            alt Cpu.is_halted
                Gb->>Cpu: is_halted = false
            end
            Gb->>Cpu: interrupt_master = false
            Gb->>Cpu: sp = sp - 2
            Gb->>Gb: write_word(sp, pc)
            Gb->>Gb: interrupt_source = get_interrupt_source(pending)
            Gb->>Gb: pc = go_interrupt(interrupt_source)
            Gb->>Gb: if_flag &= !interrupt_source
            Cpu->>Cpu: pending_cycles += 5
        end
    end

    Note over Cpu,Gb: Executing HALT instruction
    Gb->>Gb: halt()
    Gb->>Cpu: advance_pc()
    Gb->>Gb: pending = ie_flag & if_flag & 0x1F
    alt !interrupt_master && pending != 0
        Gb->>Cpu: halt_bug = true
    else
        Gb->>Cpu: is_halted = true
    end

    Note over Cpu: advance_pc with halt_bug
    Cpu->>Cpu: advance_pc()
    Cpu->>Cpu: adv = OPCODES_SIZE[current_instruction]
    alt halt_bug == true
        Cpu->>Cpu: halt_bug = false
        Cpu->>Cpu: adv = adv - 1 (saturating)
    end
    Cpu->>Cpu: pc = pc + adv

erDiagram
    CARTRIDGE_HEADER {
        string title
        string company
        integer rom_size
        integer ram_size
        string mbc_type
        boolean sgb_flag
        integer cgb_flag
    }

    CARTRIDGE_FILE {
        string file_path
        string filename
        string extension
    }

    COMPANY_CODE {
        string old_code
        string new_code
        string company_name
    }

    CARTRIDGE_FILE ||--|| CARTRIDGE_HEADER : "contains_header"
    COMPANY_CODE ||--o{ CARTRIDGE_HEADER : "decoded_to_company"

    %% Mapping functions (conceptual relationships)
    FUNCTION_load_cartridge_from_bytes {
        string rom_bytes
        string save_path
    }

    FUNCTION_get_company_name {
        string old_code
        string new_code
    }

    FUNCTION_load_cartridge_from_bytes ||--|| CARTRIDGE_HEADER : "parses_header"
    FUNCTION_get_company_name ||--|| COMPANY_CODE : "returns_name"

classDiagram
    class Gb {
        +u8 ie_flag
        +u8 if_flag
        +Cpu cpu
        +void run_one_frame()
        +void handle_interrupt()
        +void cpu_tick()
        +void components_tick()
        +void print_serial_message()
        +void set_sample_rate(u32 sample_rate)
        +[[f32;2]] get_audio_buffer()
        +[[u8;160];144] get_screen_data()
        +void write_word(u16 addr, u16 value)
    }

    class Cpu {
        +u16 pc
        +u16 sp
        +bool interrupt_master
        +bool is_halted
        +bool halt_bug
        +u8 current_instruction
        +i32 pending_cycles
        +void advance_pc()
    }

    class CartridgeHeader {
        +[u8;4] entry
        +[u8;48] logo
        +String title
        +u8 cgb_flag
        +bool sgb_flag
        +MBCTypes mbc_type
        +u32 rom_size
        +u32 ram_size
        +String company
        +new(rom_data: [u8]) Result~CartridgeHeader,&'static str~
    }

    class GbInstance {
        +static build(path: &str) Result~Gb,String~
        +static build_from_bytes(rom_data: Vec~u8~, save_path: Option~PathBuf~) Result~Gb,String~
    }

    class Serial {
        +Vec~u8~ serial_data
        +Option~String~ get_serial_message()
    }

    class JoypadButton {
        <<enum>>
        +A
        +B
        +Start
        +Select
        +Up
        +Down
        +Left
        +Right
    }

    class Mbc {
        <<trait>>
        +u8 read_rom(u16 address)
        +void write_rom(u16 address, u8 value)
        +u8 read_ram(u16 address)
        +void write_ram(u16 address, u8 value)
        +void save_ram()
    }

    class GbMode {
        <<enum>>
        +DmgMode
        +CgbMode
    }

    class GbTypes {
        <<enum>>
        +Dmg
        +Cgb
    }

    class CartridgeModule {
        +load_cartridge(filename: &str) Result~Box~dyn Mbc~,GbMode,String~
        +load_cartridge_from_bytes(rom_data: Vec~u8~, save_path: Option~PathBuf~) Result~Box~dyn Mbc~,GbMode,String~
        +get_company_name(old_code: u8, new_code: &[u8]) String
    }

    Gb o-- Cpu
    GbInstance ..> Gb
    GbInstance ..> CartridgeModule
    CartridgeModule ..> CartridgeHeader
    CartridgeModule ..> Mbc
    CartridgeHeader --> MBCTypes
    Gb --> GbMode
    Gb --> GbTypes
    Serial --> Gb
    JoypadButton <.. serde_Serialize
    JoypadButton <.. serde_Deserialize

    class serde_Serialize {
        <<trait>>
    }

    class serde_Deserialize {
        <<trait>>
    }

classDiagram
    class EmuApp {
        +Option~State~ state
        +Option~TextureHandle~ texture
        +Option~String~ error_msg
        +(Sender~Result~Vec~u8~,String~~, Receiver~Result~Vec~u8~,String~~) rom_load_channel
        +bool paused
        +SturdyConfig config
        +bool show_options
        +instant::Instant start_time
        +usize frames_rendered
        +instant::Instant last_fps_update
        +usize current_fps
        +new(cc: &CreationContext, initial_rom: Option~String~) EmuApp
        +void load_rom_file(path: &str)
        +void load_rom_bytes(bytes: Vec~u8~, save_path: Option~PathBuf~)
        +void update(ctx: &egui::Context, frame: &mut eframe::Frame)
        +void save(storage: &mut dyn eframe::Storage)
    }

    class State {
        +Gb gb
        +Vec~u8~ rgba
        +Vec~[f32;2]~ leftover_audio
        +String title
        +Vec~u8~ rom_bytes
        +Option~PathBuf~ save_path
    }

    class SturdyConfig {
        +ScaleMode scale
        +Palette palette
        +Vec~PathBuf~ rom_directories
        +HashMap~JoypadButton,egui::Key~ keybinds
        +bool fullscreen
    }

    class ScaleMode {
        <<enum>>
        +Integer(f32)
        +Stretch
    }

    class Palette {
        <<enum>>
        +Greyscale
        +ClassicGreen
        +Pocket
    }

    class GameEntry {
        +PathBuf path
        +String filename
        +String title
        +String company
    }

    class SortMethod {
        <<enum>>
        +Filename
        +Title
        +Company
    }

    class AudioGlobals {
        +static Option~SyncSender~[f32;2]~~ AUDIO_PRODUCER
        +static Option~cpal::Stream~ AUDIO_STREAM
        +setup_audio(gb: &mut Gb)
    }

    class FrontendLib {
        +APP_NAME: &str
        +extract_rom_from_bytes(bytes: &[u8]) Option~Vec~u8~~
        +set_btn(ctx: &egui::Context, state: &mut State, key: egui::Key, btn: JoypadButton)
    }

    EmuApp o-- State
    EmuApp --> SturdyConfig
    EmuApp --> GameEntry
    EmuApp --> SortMethod
    EmuApp --> AudioGlobals
    EmuApp --> FrontendLib

    State --> Gb
    State --> JoypadButton

    SturdyConfig --> ScaleMode
    SturdyConfig --> Palette
    SturdyConfig --> JoypadButton

    GameEntry --> CartridgeHeader

    AudioGlobals ..> cpal_Host
    AudioGlobals ..> cpal_Device
    AudioGlobals ..> cpal_Stream

    class cpal_Host {
        <<external>>
    }

    class cpal_Device {
        <<external>>
    }

    class cpal_Stream {
        <<external>>
    }

    class TextureHandle {
        <<external>>
    }

    class Gb {
    }

    class JoypadButton {
    }

    class CartridgeHeader {
    }